REST Interface

Authentication

REST endpoints are protected by a security layer called Resource Access Permissions that controls which endpoints each type of user can access. This article explains how to authenticate a request, how to configure these permissions, and how to set up CORS for cross-origin requests.

Sessions, JWT, OAuth and two-factor authentication are covered in detail in the Security chapter.

Authentication Methods

Structr determines the user context for each request by checking the following, in order:

1. An OAuth login flow (external authentication), which runs before all other checks
2. A session cookie, unless the request carries an Authorization header
3. A JWT in the Authorization header; when this header is present, Structr skips the session check
4. A session token in the X-StructrSessionToken header
5. The X-User and X-Password headers

If none of these yield a user, Structr treats the request as anonymous.

The X-StructrSessionToken header carries the id of an existing session, the value that the login endpoint sets as JSESSIONID cookie, so that a client without cookie support can reuse its session. Structr refuses the token when that session has timed out or no longer exists.

Header authentication is described below because it is the method used in the REST examples throughout this guide. For the other methods, see the Security chapter.

Header Authentication

Send the credentials as X-User and X-Password headers:

curl:

curl http://localhost:8082/structr/rest/Project \
  -H "X-User: admin" \
  -H "X-Password: admin"

Structr authenticates each request on its own: it verifies the credentials, resolves the user, and processes the request in that user’s context. No session is created and no token is stored, so there is nothing to expire, refresh or revoke.

That makes header authentication the simplest option for scripts, scheduled jobs and server-to-server calls. For browser applications and mobile clients, prefer sessions or JWT, which avoid transmitting the password repeatedly.

Security Considerations

Because the credentials travel with every request:

• Use HTTPS. Over plain HTTP the password is exposed on every call, not only at login. See SSL Configuration.
• Every request counts as a login attempt. Structr blocks a user after security.passwordpolicy.maxfailedattempts failed attempts (default 4). A client that retries with wrong credentials locks the account within a few requests, so treat a 401 as a stop condition rather than something to retry automatically.

Prefer a dedicated service user that holds only the permissions its client needs, rather than an administrator account. Such a user can be revoked without affecting anyone else, and a misconfigured client then blocks only that account.

Authenticating successfully does not by itself grant access to any endpoint. Access is governed by Resource Access Permissions, described next.

Resource Access Permissions

Non-admin users require explicit permission to fetch data from REST endpoints. Resource Access Permissions define which endpoints each user category can access. Consider the following request:

curl:

curl -s http://localhost:8082/structr/rest/User

Response:

{
    "code": 401,
    "message": "Access denied",
    "errors": []
}

Access to the User collection was denied. If you look at the log file, you can see a warning message because access to resources without authentication is prohibited by default:

2020-04-19 11:40:15.775 [qtp1049379734-90] INFO  o.structr.web.auth.UiAuthenticator - Found no resource access permission for anonymous users with signature 'User' and method 'GET'.

Signature

Resource Access Permissions consist of a signature and a set of flags that control access to individual REST endpoints. The signature of an endpoint is based on its URL, replacing any UUID with _id, plus a special representation for the view (the view’s name, capitalized and with a leading underscore).

The signature of a schema method or a subcollection contains the method or property name verbatim; only view names are capitalized. The following table shows examples for different URLs and the resulting signatures:

Finding the Correct Signature

If access to an endpoint is denied because of a missing Resource Access Permission, you can find the required signature in the log file:

Found no resource access permission for anonymous users with signature 'User/_id' and method 'GET'.

Flags

The flags property of a Resource Access Permission is a bitmask based on an integer value where each bit controls one permission. You can either set all flags at once with the corresponding integer value, or click the checkboxes in the Admin UI to toggle individual permissions.

Anonymous Access

With the default configuration, anonymous users cannot access any endpoints. To allow anonymous access to an endpoint, you must grant permission explicitly and separately for each HTTP method. Use the “Non-authenticated Users” flags in Resource Access Permissions for this purpose.

Without endpoint access permission:

curl -s http://localhost:8082/structr/rest/Project

{
    "code": 401,
    "message": "Access denied",
    "errors": []
}

With endpoint access permission:

curl -s http://localhost:8082/structr/rest/Project

{
    "result": [],
    "query_time": "0.000127127",
    "result_count": 0,
    "page_count": 0,
    "result_count_time": "0.000199823",
    "serialization_time": "0.001092944"
}

Now you can access the endpoint, but you still don’t see any data because no project nodes are visible for anonymous users. Visibility is controlled separately through visibility flags on each object (see User Management in the Security chapter).

Authenticated Users

With the default configuration, non-admin users cannot access any endpoints. To allow non-admin users access to an endpoint, you must grant permission explicitly and separately for each HTTP method. Use the “Authenticated Users” flags in Resource Access Permissions for this purpose.

Cross-Origin Resource Sharing (CORS)

When your frontend runs on a different domain than your Structr backend, browsers block requests by default. This security feature is called the same-origin policy. CORS headers tell browsers which cross-origin requests to allow.

When You Need CORS

CORS configuration is required when:

• Your frontend is served from a different domain than Structr
• You’re developing locally with a frontend on a different port
• You’re building a single-page application that calls the Structr API

CORS Settings

Each CORS entry configures response headers for a URL path:

Common Patterns

For development with a local frontend:

For a public API:

Configure CORS settings in the Security area of the Admin UI under the CORS tab.

Related Topics

• Security - Authentication methods, users, groups, and the permission system
• SSL Configuration - Installing SSL certificates for HTTPS
• Data Access - Once authentication is configured, this article explains how to read, create, update, and delete objects
• Admin UI / Security - How to manage users, groups, and Resource Access Permissions in the Admin UI